Crate boring

source ·
Expand description

Bindings to BoringSSL

This crate provides a safe interface to the BoringSSL cryptography library.

Versioning

Crate versioning

The crate and all the related crates (FFI bindings, etc.) are released simultaneously and all bumped to the same version disregard whether particular crate has any API changes or not. However, semantic versioning guarantees still hold, as all the crate versions will be updated based on the crate with most significant changes.

BoringSSL version

By default, the crate aims to statically link with the latest BoringSSL master branch. Note: any BoringSSL revision bumps will be released as a major version update of all crates.

Compilation and linking options

Support for pre-built binaries or custom source

While this crate can build BoringSSL on its own, you may want to provide pre-built binaries instead. To do so, specify the environment variable BORING_BSSL_PATH with the path to the binaries.

You can also provide specific headers by setting BORING_BSSL_INCLUDE_PATH.

Notes: The crate will look for headers in the $BORING_BSSL_INCLUDE_PATH/openssl/ folder, make sure to place your headers there.

In alternative a different path for the BoringSSL source code directory can be specified by setting BORING_BSSL_SOURCE_PATH which will automatically be compiled during the build process.

Warning: When providing a different version of BoringSSL make sure to use a compatible one, the crate relies on the presence of certain functions.

Building with a FIPS-validated module

Only BoringCrypto module version 853ca1ea1168dff08011e5d42d94609cc0ca2e27, as certified with FIPS 140-2 certificate 4407 is supported by this crate. Support is enabled by this crate’s fips feature.

boring-sys comes with a test that FIPS is enabled/disabled depending on the feature flag. You can run it as follows:

$ cargo test --features fips fips::is_enabled

Linking current BoringSSL version with precompiled FIPS-validated module (bcm.o)

It’s possible to link latest supported version of BoringSSL with FIPS-validated crypto module (bcm.o). To enable this compilation option one should enable fips-link-precompiled compilation feature and provide a BORING_SSL_PRECOMPILED_BCM_O env variable with a path to the precompiled FIPS-validated bcm.o module.

Optional patches

Raw Public Key

The crate can be compiled with RawPublicKey support by turning on rpk compilation feature.

Experimental post-quantum cryptography

The crate can be compiled with post-quantum cryptography support by turning on post-quantum compilation feature.

Upstream BoringSSL support the post-quantum hybrid key agreement X25519Kyber768Draft00. Most users should stick to that one. Enabling this feature, adds a few other post-quantum key agreements:

  • X25519Kyber768Draft00Old is the same as X25519Kyber768Draft00, but under its old codepoint. -X25519Kyber512Draft00. Similar to X25519Kyber768Draft00, but uses level 1 parameter set for Kyber. Not recommended. It’s useful to test whether the shorter ClientHello upsets fewer middle boxes.
  • P256Kyber768Draft00. Similar again to X25519Kyber768Draft00, but uses P256 as classical part. It uses a non-standard codepoint. Not recommended.

Presently all these key agreements are deployed by Cloudflare, but we do not guarantee continued support for them.

Modules

  • aes
    Low level AES IGE and key wrapping functionality
  • asn1
    Defines the format of certificiates
  • base64
    Base64 encoding support.
  • bn
    BigNum implementation
  • conf
    Interface for processing OpenSSL configuration files.
  • derive
    Shared secret derivation.
  • dh
  • dsa
    Digital Signatures
  • ec
    Elliptic Curve
  • ecdsa
    Low level Elliptic Curve Digital Signature Algorithm (ECDSA) functions.
  • error
    Errors returned by OpenSSL library.
  • ex_data
  • fips
    FIPS 140-2 support.
  • hash
  • memcmp
    Utilities to safely compare cryptographic values.
  • nid
    A collection of numerical identifiers for OpenSSL objects.
  • pkcs5
  • pkcs12
    PKCS #12 archives.
  • pkey
    Public/private key processing.
  • rand
    Utilities for secure random number generation.
  • rsa
    Rivest–Shamir–Adleman cryptosystem
  • sha
    The SHA family of hashes.
  • sign
    Message signatures.
  • srtp
  • ssl
    SSL/TLS support.
  • stack
  • string
  • symm
    High level interface to certain symmetric ciphers.
  • version
  • x509
    The standard defining the format of public key certificates.

Functions